# Fetching a list of Custom Field Values

Returns all values for the specified set of
[Custom Fields](https://mavenlink.zendesk.com/hc/en-us/articles/202924760-Custom-Fields-Overview-#arrange).
This endpoint has its own rate limit. See the [Knowledge Base](https://knowledge.kantata.com/hc/en-us/articles/9698066628123) for more information.
Custom fields are organized into [sets](/tag/Custom-Field-Sets),
by the objects they store additional information for (Estimate, Project, Group, Resource, Task, or User).
Use the `subject_type` parameter to specify which set of Custom Fields to return values for:
* `Estimate`
* `Story` (Task)
* `User`
* `Workspace` (Project)
* `WorkspaceGroup` (Group)
* `Resource`

Custom field values for *archived* Projects and Tasks are included in returned values.
Values are sorted from less to more recently updated.
##### Note:
The `read_access` [permission setting on each custom field](https://mavenlink.zendesk.com/hc/en-us/articles/202924760#see)
determines the minimum permission needed to view a custom field and its value.
* `Workspace` (Project), `Resource`, and `Story` (Task) custom fields are project-specific objects,
so their minimum permissions are set at the [project level](https://mavenlink.zendesk.com/hc/en-us/articles/115002779293-Project-Permissions):
  - `project_collaboration` (default)
  - `time_logging`
  - `financial`
  - `project_admin`

Most account-level permissions supercede project-level permissions. Therefore, Account Administrators
are able to view all Project, Resource, and Task custom fields and values across the account,
regardless of project participation or `read_access` settings.
* `Estimate`, `WorkspaceGroup` (Group), and `User` custom fields are account-wide objects, so their minimum permissions are
set at the [account level](https://mavenlink.zendesk.com/hc/en-us/articles/203041364):
  - `account_collaboration`
  - `project_creator`
  - `project_lead`
  - `reports_viewer`
  - `reports_viewer_with_cost`
  - `account_admin` (default)

This endpoint returns structured Custom Field Value objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `custom_field_values` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

Endpoint: GET /custom_field_values
Version: 1.0.0

## Query parameters:

  - `subject_type` (string, required)
    You must specify which set of Custom Fields to return values for:
* `Estimate`
* `Story` (Task)
* `User`
* `Workspace` (Project)
* `WorkspaceGroup` (Group)
* `Resource`

This parameter is required.

  - `created_after` (string)
    Filter for records created after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `created_before` (string)
    Filter for records created before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `external_reference_external_message` (string)
    Filter the objects based on the external message of their associated external references. This is an exact match.

  - `external_reference_external_status` (string)
    Filter by the status of the external object in the external system.

  - `external_reference_service_model` (string)
    Filter by the type of the external object this external reference belongs to.

  - `external_reference_service_model_ref` (integer)
    Filter by the id of the external object this external reference belongs to.

  - `external_reference_service_model_refs` (string)
    Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs.

  - `external_reference_service_name` (string)
    Filter by the name of the provider for integration.

  - `external_reference_status` (string)
    Filter by the status of the integration, this can be successful or fail.

  - `has_external_references` (boolean)
    Filter by whether or not the object has external references.

  - `include` (string)
    Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `custom_field` (CustomField) - Retrieves the custom field the value is for. The response will include `custom_field_id`, which references the data in the `custom_fields` top-level key.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.
- `selected_choices` (CustomFieldChoice) - Retrieves the custom field choice that corresponds to the custom field value. The response will include `selected_choice_ids`, which references the data in the `custom_field_choices` top-level key.
- `setter` (User) - Retrieves the user that set the custom field value. The response will include `setter_id`, which references the data in the `users` top-level key.
- `subject` (polymorphic) - Retrieves the object which the custom field value is for. The response will include `subject_ref`, which references the data in the top-level key specified in the `key` field of `subject_ref`. The possible objects are as follows:
* `Estimate`
* `Workspace` (Project)
* `WorkspaceGroup` (Group)
* `Resource`
* `Story` (Task)
* `User`.

  - `only` (string)
    Allows you to request one or more resources directly by ID. Multiple IDs can be supplied
in a comma separated list, like `GET /api/v1/workspaces.json?only=5,6,7`.

  - `order` (string)
    Supply `order` with the name of a valid sort field for the endpoint and a direction.

Valid values: `created_at:asc`, `created_at:desc`, `subject_id:asc`, `subject_id:desc`, `updated_at:asc`, and `updated_at:desc`.

  - `page` (integer)

  - `per_page` (integer)

  - `updated_after` (string)
    Filter for records updated after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `updated_before` (string)
    Filter for records updated before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `with_custom_field_id` (string)
    Filters for values of the Custom Field(s) with the specified ID(s). Give multiple Custom Field IDs in a comma-separated list.

  - `with_setter_id` (string)
    Filters for Custom Field Values set by a user with the specified ID(s). Give multiple user IDs in a comma-separated list.

  - `with_subject_id` (string)
    Filters for Custom Field Values associated with the specified ID(s) of an Estimate, Project,
             Group, Resource, Task, or User. Give multiple IDs in a comma-separated list.

  - `without_external_reference_service_name` (string)
    Exclude by the existence of an external reference with the specified service name.

## Response 200 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.id` (string)

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 403 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 422 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)